<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Realm chains | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="setting-up-authentication.html" title="User authentication">
<link rel="prev" href="realms.html" title="Realms">
<link rel="next" href="active-directory-realm.html" title="Active Directory user authentication">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="setting-up-authentication.html">User authentication</a></span>
»
<span class="breadcrumb-node">Realm chains</span>
</div>
<div class="navheader">
<span class="prev">
<a href="realms.html">« Realms</a>
</span>
<span class="next">
<a href="active-directory-realm.html">Active Directory user authentication »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="realm-chains"></a>Realm chains<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/realm-chains.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>
<p><a class="xref" href="realms.html" title="Realms">Realms</a> live within a <em>realm chain</em>. It is essentially a prioritized
list of configured realms (typically of various types). Realms are consulted in
ascending order (that is to say, the realm with the lowest <code class="literal">order</code> value is
consulted first). You should make sure each configured realm has a distinct
<code class="literal">order</code> setting. In the event that two or more realms have the same <code class="literal">order</code>,
they are processed in <code class="literal">name</code> order.</p>
<p>During the authentication process, Elastic Stack security features consult and try
to authenticate the request one realm at a time. Once one of the realms
successfully authenticates the request, the authentication is considered to be
successful. The authenticated user is associated with the request, which then
proceeds to the authorization phase. If a realm cannot authenticate the request,
the next realm in the chain is consulted. If all realms in the chain cannot
authenticate the request, the authentication is considered to be unsuccessful
and an authentication error is returned (as HTTP status code <code class="literal">401</code>).</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Some systems (e.g. Active Directory) have a temporary lock-out period
after several successive failed login attempts. If the same username exists in
multiple realms, unintentional account lockouts are possible. For more
information, see <a class="xref" href="trouble-shoot-active-directory.html" title="Users are frequently locked out of Active Directory">Users are frequently locked out of Active Directory</a>.</p>
</div>
</div>
<p>The default realm chain contains the <code class="literal">native</code> and <code class="literal">file</code> realms. To explicitly
configure a realm chain, you specify the chain in the <code class="literal">elasticsearch.yml</code> file.
When you configure a realm chain, only the realms you specify are used for
authentication. To use the <code class="literal">native</code> and <code class="literal">file</code> realms, you must include them in
the chain.</p>
<p>The following snippet configures a realm chain that includes the <code class="literal">file</code> and
<code class="literal">native</code> realms, as well as two LDAP realms and an Active Directory realm.</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack.security.authc.realms:
  file.file1:
      order: 0

  native.native1:
      order: 1

  ldap.ldap1:
      order: 2
      enabled: false
      url: 'url_to_ldap1'
      ...

  ldap.ldap2:
      order: 3
      url: 'url_to_ldap2'
      ...

  active_directory.ad1:
      order: 4
      url: 'url_to_ad'</pre>
</div>
<p>As can be seen above, each realm has a unique name that identifies it. Each type
of realm dictates its own set of required and optional settings. That said,
there are
<a href="/guide/en/elasticsearch/reference/7.7/security-settings.html#ref-realm-settings" class="ulink" target="_top">settings that are common to all realms</a>.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="authorization_realms"></a>Delegating authorization to another realm<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/realm-chains.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Some realms have the ability to perform <em>authentication</em> internally, but
delegate the lookup and assignment of roles (that is, <em>authorization</em>) to
another realm.</p>
<p>For example, you may wish to use a PKI realm to authenticate your users with
TLS client certificates, then lookup that user in an LDAP realm and use their
LDAP group assignments to determine their roles in Elasticsearch.</p>
<p>Any realm that supports retrieving users (without needing their credentials) can
be used as an <em>authorization realm</em> (that is, its name may appear as one of the
values in the list of <code class="literal">authorization_realms</code>). See <a class="xref" href="run-as-privilege.html" title="Submitting requests on behalf of other users">Submitting requests on behalf of other users</a> for
further explanation on which realms support this.</p>
<p>For realms that support this feature, it can be enabled by configuring the
<code class="literal">authorization_realms</code> setting on the authenticating realm. Check the list of
<a href="/guide/en/elasticsearch/reference/7.7/security-settings.html#realm-settings" class="ulink" target="_top">supported settings</a> for each realm
to see if they support the <code class="literal">authorization_realms</code> setting.</p>
<p>If delegated authorization is enabled for a realm, it authenticates the user in
its standard manner (including relevant caching) then looks for that user in the
configured list of authorization realms. It tries each realm in the order they
are specified in the <code class="literal">authorization_realms</code> setting. The user is retrieved by
principal - the user must have identical usernames in the <em>authentication</em> and
<em>authorization realms</em>. If the user cannot be found in any of the authorization
realms, authentication fails.</p>
<p>See <a class="xref" href="configuring-authorization-delegation.html" title="Configuring authorization delegation">Configuring authorization delegation</a> for more details.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Delegated authorization requires a
<a href="/subscriptions" class="ulink" target="_top">Platinum or Trial license</a>.</p>
</div>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="realms.html">« Realms</a>
</span>
<span class="next">
<a href="active-directory-realm.html">Active Directory user authentication »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
